ZK Processing Instructions

This documentation is for an older version of ZK. For the latest one, please click here.

Directives to control whole page behavior

Processing Instruction Name	Description
page	Describes attributes of a page
component	Defines a new component for a particular page

Overview

The XML processing instructions describe how to process the ZUML page. Here we list the most used directives. For the complete list of all directives, please refer to the Developer's Reference.

The page Directive

 <?page [id="..."] [title="..."] [style="..."][language="xul/html"]?>

It describes attributes of a page.

Note: You can place the page directive in any location of a XML document, but the language attribute is meaningful only if the directive is located at the topmost level, i.e., at the the same level as the root element.

Remember to use the page directive if you want to use java code to access component by absolute path, like

Path.getComponent("//P/A/C/E");//for page, you have to use // as prefix

For more available options and descriptions, refer to the Component Reference.

The component Directive

 <?component name="myName" macroURI="/mypath/my.zul"
   [prop1="value1"] [prop2="value2"]...?>
 <?component name="myName" [class="myPackage.myClass"]
   [extends="existentName"] [moldName="myMoldName"] [moldURI="/myMoldURI"]
   [prop1="value1"] [prop2="value2"]...?>

Defines a new component for a particular page. It can be a macro from a separate zul file or a extending class from existing component. Components defined in this directive is visible only to the page with this directive.

---

There are two formats: by-macro and by-class.

The by-macro Format

 <?component name="myName" macroURI="/mypath/my.zul" [inline="true|'false'"]
    [class="myPackage.myClass"] [prop1="value1"] [prop2="value2"]...?>

Defines a new component based on a ZUML page. It is called a macro component. In other words, once an instance of the new component is created, it creates child components based on the specified ZUML page (the macroURI attribute). It's useful to divide a big zul file to separate single function little zul files. It's easier to maintain and test.

For example: A zul file name as: /WEB-INF/macros/username.zul

<hbox>
	Username: <textbox/>
</hbox>

Then we can use it as a macro component as following example shows:

<?component name="username" macroURI="/WEB-INF/macros/username.zul"?>
<window>
	<username/>
</window>

For more details, refer to the Macro Components chapter.

The by-class Format

 <?component name="myName" [class="myPackage.myClass"]
   [extends="existentName"] [moldName="myMoldName"] [moldURI="/myMoldURI"]
   [prop1="value1"] [prop2="value2"]...?>

Defines a new component. If the extends attribute is not specified, it is called a primitive component. The class must implement the Component interface.

To define a new component, you have to specify at least the class attribute, which is used by ZK to instantiate a new instance of the component.

In addition to defining a brand-new component, you can override properties of existent components by specifying extends="existentName". In other words, if extends is specified, the definition of the specified component is loaded as the default value and then override only properties that are specified in this directive.

For example, assume you want to define a new component called mywindow by use of MyWindow instead of the default window, Window in a ZUML page. Then, you can declare it as follows.

 <?component name="mywindow" extends="window" class="MyWindow"?>
 ...
 <mywindow>
 ...
 </mywindow>

It is equivalent to the following codes.

 <window use="MyWindow">
 ...
 </window>

Similarly, you could use the following definition to use OK as the default label and a blue border for all buttons specified in this page.

 <?component name="okbutton" extends="button" label="OK"
   style="border:1px solid blue"?>

Notice the new component name can be the same as the existent one. In this case, all instances of the specified type of component will use the initial properties you assigned, as if it hides the existent definition. For example, the following codes make all buttons to have a blue border as default.

 <?component name="button" extends="button" style="border:1px solid blue"?>
 <button/> <!-- with blue border -->

For more information, refer to the Component Reference.

Quiz

1.Please visit the Component Reference and look up what value is accepted by zscriptLanguage

2.Assume following macro zul, write a zul to use it.

username.zul

<row>
	Username
	<textbox/>
</row>